home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kopete / kopetepluginmanager.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  7.3 KB  |  247 lines
  1. /*
  2.     kopetepluginmanager.h - Kopete Plugin Loader
  3.  
  4.     Copyright (c) 2002-2003 by Duncan Mac-Vicar Prett <duncan@kde.org>
  5.     Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
  6.  
  7.     Kopete    (c) 2002-2003 by the Kopete developers  <kopete-devel@kde.org>
  8.  
  9.     *************************************************************************
  10.     *                                                                       *
  11.     * This library is free software; you can redistribute it and/or         *
  12.     * modify it under the terms of the GNU Lesser General Public            *
  13.     * License as published by the Free Software Foundation; either          *
  14.     * version 2 of the License, or (at your option) any later version.      *
  15.     *                                                                       *
  16.     *************************************************************************
  17. */
  18.  
  19. #ifndef KOPETEPLUGINMANAGER_H
  20. #define KOPETEPLUGINMANAGER_H
  21.  
  22. #include <qmap.h>
  23. #include <qobject.h>
  24. #include <qstring.h>
  25. #include <qstringlist.h>
  26. #include <qvaluelist.h>
  27.  
  28. #include "kopete_export.h"
  29.  
  30. class KPluginInfo;
  31.  
  32. namespace Kopete
  33. {
  34.  
  35. class Plugin;
  36.  
  37. typedef QValueList<Plugin*> PluginList;
  38.  
  39. /**
  40.  * @author Duncan Mac-Vicar Prett <duncan@kde.org>
  41.  * @author Martijn Klingens <klingens@kde.org>
  42.  */
  43. class KOPETE_EXPORT PluginManager : public QObject
  44. {
  45.     Q_OBJECT
  46.     Q_ENUMS( PluginLoadMode )
  47.  
  48. public:
  49.     /**
  50.      * Retrieve the plugin loader instance.
  51.      */
  52.     static PluginManager* self();
  53.  
  54.     ~PluginManager();
  55.  
  56.     /**
  57.      * Returns a list of all available plugins for the given category.
  58.      * Currently there are two categories, "Plugins" and "Protocols", but
  59.      * you can add your own categories if you want.
  60.      *
  61.      * If you pass an empty string you get the complete list of ALL plugins.
  62.      *
  63.      * You can query all information on the plugins through the KPluginInfo
  64.      * interface.
  65.      */
  66.     QValueList<KPluginInfo *> availablePlugins( const QString &category = QString::null ) const;
  67.  
  68.     /**
  69.      * Returns a list of all plugins that are actually loaded.
  70.      * If you omit the category you get all, otherwise it's a filtered list.
  71.      * See also @ref availablePlugins().
  72.      */
  73.     PluginList loadedPlugins( const QString &category = QString::null ) const;
  74.  
  75.     /**
  76.      * @brief Search by plugin name. This is the key used as X-KDE-PluginInfo-Name in
  77.      * the .desktop file, e.g. "kopete_jabber"
  78.      *
  79.      * @return The @ref Kopete::Plugin object found by the search, or a null
  80.      * pointer if the plugin is not loaded.
  81.      *
  82.      * If you want to also load the plugin you can better use @ref loadPlugin, which returns
  83.      * the pointer to the plugin if it's already loaded.
  84.      */
  85.     Plugin *plugin( const QString &pluginName ) const;
  86.  
  87.     /**
  88.      * @return the KPluginInfo for the specified plugin
  89.      */
  90.     KPluginInfo *pluginInfo( const Kopete::Plugin *plugin ) const;
  91.  
  92.  
  93.     /**
  94.      * Shuts down the plugin manager on Kopete shutdown, but first
  95.      * unloads all plugins asynchronously.
  96.      *
  97.      * After 3 seconds all plugins should be removed; what's still left
  98.      * by then is unloaded through a hard delete instead.
  99.      *
  100.      * Note that this call also derefs the plugin manager from the event
  101.      * loop, so do NOT call this method when not terminating Kopete!
  102.      */
  103.     void shutdown();
  104.  
  105.     /**
  106.      * Enable a plugin.
  107.      *
  108.      * This marks a plugin as enabled in the config file, so loadAll()
  109.      * can pick it up later.
  110.      *
  111.      * This method does not actually load a plugin, it only edits the
  112.      * config file.
  113.      *
  114.      * @param name is the name of the plugin as it is listed in the .desktop
  115.      * file in the X-KDE-Library field.
  116.      * @param enabled sets whether or not the plugin is enabled
  117.      *
  118.      * Returns false when no appropriate plugin can be found.
  119.      */
  120.     bool setPluginEnabled( const QString &name, bool enabled = true );
  121.  
  122.     /**
  123.      * This method check if all the plugins are loaded.
  124.      * @return true if all the plugins are loaded.
  125.      */
  126.     bool isAllPluginsLoaded() const;
  127.  
  128.     /**
  129.      * Plugin loading mode. Used by @ref loadPlugin(). Code that doesn't want to block
  130.      * the GUI and/or lot a lot of plugins at once should use asynchronous loading (@c LoadAsync).
  131.      * The default is synchronous loading (@c LoadSync).
  132.      */
  133.     enum PluginLoadMode { LoadSync, LoadAsync };
  134.  
  135. public slots:
  136.     /**
  137.      * @brief Load a single plugin by plugin name. Returns an existing plugin
  138.      * if one is already loaded in memory.
  139.      *
  140.      * If mode is set to Async, the plugin will be queued and loaded in
  141.      * the background. This method will return a null pointer. To get
  142.      * the loaded plugin you can track the @ref pluginLoaded() signal.
  143.      *
  144.      * See also @ref plugin().
  145.      */
  146.     Plugin *loadPlugin( const QString &pluginId, PluginLoadMode mode = LoadSync );
  147.  
  148.     /**
  149.      * @brief Unload the plugin specified by @p pluginName
  150.      */
  151.     bool unloadPlugin( const QString &pluginName );
  152.  
  153.     /**
  154.      * @brief Loads all the enabled plugins. Also used to reread the
  155.      * config file when the configuration has changed.
  156.      */
  157.     void loadAllPlugins();
  158.  
  159. signals:
  160.     /**
  161.      * @brief Signals a new plugin has just been loaded.
  162.      */
  163.     void pluginLoaded( Kopete::Plugin *plugin );
  164.  
  165.     /**
  166.      * @brief All plugins have been loaded by the plugin manager.
  167.      *
  168.      * This signal is emitted exactly ONCE, when the plugin manager has emptied
  169.      * its plugin queue for the first time. This means that if you call an async
  170.      * loadPlugin() before loadAllPlugins() this signal is probably emitted after
  171.      * the initial call completes, unless you are quick enough to fill the queue
  172.      * before it completes, which is a dangerous race you shouldn't count upon :)
  173.      *
  174.      * The signal is delayed one event loop iteration through a singleShot timer,
  175.      * but that is not guaranteed to be enough for account instantiation. You may
  176.      * need an additional timer for it in the code if you want to programmatically
  177.      * act on it.
  178.      *
  179.      * If you use the signal for enabling/disabling GUI objects there is little
  180.      * chance a user is able to activate them in the short while that's remaining,
  181.      * the slow part of the code is over now and the remaining processing time
  182.      * is neglectable for the user.
  183.      */
  184.     void allPluginsLoaded();
  185.  
  186. private slots:
  187.     /**
  188.      * @brief Cleans up some references if the plugin is destroyed
  189.      */
  190.     void slotPluginDestroyed( QObject *plugin );
  191.  
  192.     /**
  193.      * shutdown() starts a timer, when it fires we force all plugins
  194.      * to be unloaded here by deref()-ing the event loop to trigger the plugin
  195.      * manager's destruction
  196.      */
  197.     void slotShutdownTimeout();
  198.  
  199.     /**
  200.      * Common entry point to deref() the KApplication. Used both by the clean
  201.      * shutdown and the timeout condition of slotShutdownTimeout()
  202.      */
  203.     void slotShutdownDone();
  204.  
  205.     /**
  206.      * Emitted by a Kopete::Plugin when it's ready for unload
  207.      */
  208.     void slotPluginReadyForUnload();
  209.  
  210.     /**
  211.      * Load a plugin from our queue. Does nothing if the queue is empty.
  212.      * Schedules itself again if more plugins are pending.
  213.      */
  214.     void slotLoadNextPlugin();
  215.  
  216. private:
  217.     /**
  218.      * @internal
  219.      *
  220.      * The internal method for loading plugins.
  221.      * Called by @ref loadPlugin directly or through the queue for async plugin
  222.      * loading.
  223.      */
  224.     Plugin * loadPluginInternal( const QString &pluginId );
  225.  
  226.     /**
  227.      * @internal
  228.      *
  229.      * Find the KPluginInfo structure by key. Reduces some code duplication.
  230.      *
  231.      * Returns a null pointer when no plugin info is found.
  232.      */
  233.     KPluginInfo * infoForPluginId( const QString &pluginId ) const;
  234.  
  235.     PluginManager();
  236.  
  237.     class Private;
  238.     Private *d;
  239.     static PluginManager *s_self;
  240. };
  241.  
  242. }
  243.  
  244. #endif // KOPETEPLUGINMANAGER_H
  245.  
  246. // vim: set noet ts=4 sts=4 sw=4:
  247.